home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / src / X11 / tclMotif-1.4 / send / userman.txt < prev   
Text File  |  1995-06-29  |  7KB  |  186 lines
  1.                        "send" for Xt User Manual
  2.                        -------------------------
  3.  
  4. Introduction
  5. ------------
  6. Applications in the X world can use a number of X based mechanisms to
  7. communicate with each other. The most common is to use ``selections'' and
  8. cut buffers. These are ultimately based on X Properties that can be
  9. attached to windows.
  10.  
  11. In the Tk set of widgets, another communication protocol was introduced. In
  12. this, a Tk application can ``send'' commands to another Tk application. A
  13. Tk based application is generally built using the programming language tcl,
  14. and the messages actually consist of tcl commands from the first
  15. application to the second. This causes the second application to execute
  16. the command, possibly invoking communications with other applications.
  17.  
  18. The use of Tk is not essential for this to work - any set of widgets in X
  19. world can use this mechanism. It is also implemented using the X Properties
  20. system. This package is an implementation of ``send'' for Xt based
  21. applications.
  22.  
  23.  
  24. Using ``send'' in tcl
  25. ---------------------
  26. tcl is a type-free interpreted language that uses strings for everything.
  27. It is intended as a language that can be embedded into applications
  28. requiring a command language. The language supplies a syntax and a
  29. semantics, and this is realised by an interpreter that can be created by
  30. an application. New tcl commands can be defined by the application that
  31. will call application code when executed by the interpreter. Information
  32. can be examined and set in the interpreter.
  33.  
  34. An extension introduced by the Tk toolkit allows one interpreter to execute
  35. commands in another one. Each interpreter is given a global name within the
  36. X world. One interpreter can send a command to another one using its name:
  37.  
  38. send you_over_there do_this_command
  39.  
  40. For example, a debugger could send a message to an editor
  41.  
  42. send editor {display_line 42}
  43.  
  44. The command will be attempted in the other interpreter. This is done
  45. synchronously, and any result is sent back to the first interpreter. If the
  46. first interpreter does not receive an reply in a reasonable time (5
  47. seconds) ``send'' times out with an error value.
  48.  
  49. This allows small applications to co-operatively execute, much like small
  50. character based Unix applications do.
  51.  
  52. ``send'' and Xt
  53. ---------------
  54. This package allows an Xt application to send tcl commands to any
  55. application that understands the ``send'' protocol, and in turn it will
  56. receive and execute tcl commands sent to it. Both the sending and the
  57. execution are performed through a tcl interpreter, so the Xt application
  58. first has to create such an interpreter. This is done by the function call
  59.  
  60. #include <tcl.h>
  61.  
  62. Tcl_Interp *Tcl_CreateInterp(void);
  63.  
  64. This returns a pointer to a tcl interpreter which will be used in all
  65. successive calls to the tcl system.
  66.  
  67. More than one interpreter may be created, but most applications would only
  68. create one.
  69.  
  70.  
  71. Registering a tcl interpreter
  72. -----------------------------
  73. Before an interpreter can be used to send or receive commands, it must be
  74. registered so that its name is globally known. Any name can be used. A
  75. convention in Tk based applications is that this will be the name of the
  76. application, if possible. This allows the user of these applications to see
  77. the interpreter name as the name shown by the window manager.
  78.  
  79. There can only be one name per interpreter because of the way ``send'' was
  80. implemented originally.
  81.  
  82. A name exists on the server's root window, so interpreter names must be
  83. unique on a display. An attempt to register a name that is already in use
  84. will fail.
  85.  
  86. Registering an interpreter is done by 
  87.  
  88. #include <tcl.h>
  89. #include <tclXtSend.h>
  90.  
  91. int TclXtSend_RegisterInterp(Tcl_Interp *interp, char *name, Widget toplevel);
  92.  
  93. The widget argument can be any widget, but will normally be the widget
  94. returned from the XtAppInitialize function. The return value of the
  95. function will either be TCL_OK or TCL_ERROR.
  96.  
  97. [The rather gross name arise from trying to find a reasonable naming
  98. convention. Tcl_, Tk_, Xt, X, etc are all reserved by the various toolkits.
  99. TclXtSend_ shows the origins and does not clash with other names. You only
  100. have to type it once per application, anyway.]
  101.  
  102. Communicating with the interpreter from the application
  103. -------------------------------------------------------
  104. The simplest way to get the interpreter to execute a command from an
  105. application is to call Tcl_Eval with the command as the second argument.
  106. For example,
  107.  
  108. Tcl_Eval(interp, "puts stdout {hello world}");
  109.  
  110. This mechanism can be used unaltered to send a message: the command is now
  111. a ``send'' command:
  112.  
  113. Tcl_Eval(interp, "send editor {display_line 42}");
  114.  
  115. The function returns TCL_OK if it succeeds, and TCL_ERROR if it fails. If
  116. it fails, an error message will be in interp->result.
  117.  
  118. Communicating with the interpreter via ``send''
  119. ----------------------------------------------
  120. Once an interpreter has been registered, another application can use the
  121. send protocol to cause it to execute commands. Nothing extra has to be
  122. done.
  123.  
  124. Interpreter state
  125. -----------------
  126. The tcl interpreter maintains the state of the tcl variables known to it.
  127. The value of one of these can be examined using Tcl_GetVar, and set using
  128. Tcl_SetVar.
  129.  
  130. New commands can be defined purely internally to the tcl interpreter using
  131. the Tcl_Eval function, where the string to be executed defines a tcl
  132. procedure:
  133.  
  134. Tcl_Eval(interp, "proc hello {} {puts stdout {hello world}}");
  135.  
  136. Application commands
  137. --------------------
  138. The interpreter can be extended by new commands which call execution code
  139. by the Tcl_CreateCommand. This takes as arguments the interpreter, the
  140. command name, the C function to execute when the interpreter executes the
  141. command, client data that can be passed to the C function, and a destroy
  142. function if needed.
  143.  
  144. Examples
  145. --------
  146. Supposing you want to send a message to another interpreter when a callback
  147. occurs. For example, a command panel listing all interpreters could send an
  148. ``exit'' message to an interpreter when its button is pressed.
  149.  
  150. In the client data of the button, place the interpreter. This ensures that
  151. it is ``local'' data rather than mucky global stuff:
  152.  
  153. XtAddCallback(w, XmNactivateCallback, KillCB, (XtPointer) interp);
  154.  
  155. Within the callback, extract the interpreter and send the message (say to
  156. interpreter ``abcd'')
  157.  
  158. interp = (Tcl_Interp *) client_data;
  159. Tcl_Eval(interp, "send abcd exit");
  160.  
  161. On the other hand, if you are the application that may be in receipt of
  162. such a message, you may want to handle this in a graceful way. So your
  163. application creates a new command to call your C code when this happens:
  164.  
  165. Tcl_CreateCommand(interp, "exit", ExitGracefully, NULL, NULL);
  166.  
  167. int ExitGracefully(ClientData *clientdata, Tcl_Interp *interp,
  168.     int argc, char **argv)
  169. {
  170.     /* tidy up the application */
  171.     /* .... */
  172.  
  173.     Tcl_DeleteInterp(interp);
  174.     exit(0);
  175. }
  176.  
  177. Implementation
  178. --------------
  179. The implementation is identical to Tk: create an unmapped window in each
  180. application known as ``_comm''. Properties are attached to this window to
  181. receive the message, while an event handler waits on this window for a
  182. PropertyNotify message.
  183.  
  184. The root window maintains a list of interpreters and their corresponding
  185. windows in the property ``InterpRegistry''. This is updated on each change.
  186.